Skip to main content
Version: v2.10.0

Create Cluster

A Yeedu cluster is the compute unit that runs your jobs and notebooks. This page documents every field on the New Cluster form as it appears in Yeedu v2.10.1.

Accessing Cluster Creation

  • Navigate to Clusters in the tenant navigation panel.
  • Click the + Cluster button (top-right, above the Actions column).
  • The form opens at /tenant/<tenant-id>/create-cluster with the breadcrumb Clusters > New Cluster.

Create Button

The page uses a two-column layout:

  • Left column – the cluster configuration form.
  • Right column – a live CLUSTER DETAILS summary card that updates as you fill the form.

Create Cluster

Field Order

The form presents fields in this order. Fields marked * are required.

#FieldControl
1Cluster Name*Text
2DescriptionTextarea
3Cluster Type*Dropdown
4Cloud Environment*Dropdown + inline create
5Acceleration*Radio group
6Dependency RepositoryDropdown (clearable) + inline create
7Run Time Version*Dropdown
8Compute*Select Compute modal
9Min Instances* / Max Instances* / Number of Parallel Execution*Numeric
10Auto ShutdownNumeric (minutes)
11LabelsKey/value rows
12MetastoreDropdown + inline create
13Mounts, Spark Config, Advanced OptionsCollapsible sections

Basic Details

Cluster Name

  • Required. Placeholder: example_cluster_1.
  • Max length: 64 characters.
  • Allowed: lowercase letters, -, _, @, .

Description

  • Optional free-text description of the cluster.

Cluster Type

The Cluster Type dropdown offers exactly three values (these are the literal values shown in the UI and used by the Cluster Type filter on the Clusters list):

ValueNotes
YEEDUFully managed Spark environment optimized for CPU performance; runs Spark in local mode.
STANDALONEStandalone Spark deployment.
CLUSTERCluster-mode Spark deployment.

Note: Cluster type cannot be modified after creation.

Cloud Environment

The Cloud Environment* dropdown selects an existing cloud environment. Alongside the dropdown are:

  • Open in new – opens the selected cloud environment in a new tab.
  • Show details (eye) – expands the environment's details inline.
  • + – opens the Create Cloud Environment modal without leaving the form.

Supported cloud providers

Yeedu v2.10.1 supports five providers:

ProviderNotes
OCIOracle Cloud Infrastructure.
OnPremOn-premises environment backed by Proxmox VE.
GCPGoogle Cloud Platform.
AWSAmazon Web Services.
AzureMicrosoft Azure.

Cloud environment fields

Every cloud environment has these common fields:

  • Cloud Environment Name*
  • Description
  • Cloud Provider*
  • Credential*
  • Network*
  • Boot Disk Image*
  • Labels

The remaining fields depend on the provider:

ProviderProvider-specific fields
OCIAvailability Domain*
OnPremEnd Point* (for example https://onprem-host:8006/, the Proxmox VE port) and OnPrem Nodes* (select nodes, with a Fetch Nodes action)
GCPAvailability Zone*, Project ID*
AWSAvailability Zone*, Account ID*
AzureAvailability Zone*, Resource Group*

Credential types

When creating a credential inline, the Cloud Provider is locked to the parent form's provider. Each provider exposes exactly one credential type, except OnPrem, which exposes two.

ProviderCredential TypeFields
OCIOCI API Key PairTenancy OCID*, User OCID*, Fingerprint*, Compartment OCID*, Private Key File* (.pem upload / drag-and-drop)
OnPremProxmox Basic AuthUsername* (the UI appends @pam to the username), Password*
OnPremCustom S3a CredentialsAccess Key ID*, Custom S3a Endpoint*, Secret Access Key*
GCPGoogle Service AccountCredentials* (service-account JSON)
AWSAWS Access Secret Key PairAccess Key ID*, Default Region* (dropdown), Secret Access Key*
AzureAzure Service PrincipalClient ID*, Tenant ID*, Client Secret*, Subscription ID*, Storage Account Name*, Container Name*

Cloud Permissions Required by Each Credential

The credential you attach to a cloud environment is the principal Yeedu acts as. Our provisioning engine uses it in two passes: Terraform creates and destroys the node, its disks and its network attachment, and the cloud SDK then starts, stops and inspects that node for the rest of its life.

Everything below comes from the Terraform we actually run, one module per cloud, plus the SDK calls the engine makes around it. So the tables are short on purpose. We never create a VPC, a subnet, a security group, a resource group or a Proxmox datastore for you, because those are inputs you supply on the cloud environment and we only read them.

Missing permissions surface late. The form accepts the credential and the failure lands during cluster bootstrap, not at submit time.

Credential typeCloudWhat the credential provisions
OCI API Key PairOCICompute instances, block volumes, a VNIC on your subnet
Proxmox Basic AuthOnPremProxmox VE guests, their disks, a cloud-init snippet
Custom S3a CredentialsOnPremNothing. Object storage access only
Google Service AccountGCPCompute instances, persistent disks, a reserved internal address
AWS Access Secret Key PairAWSEC2 instances, EBS volumes, an imported key pair, CloudWatch log groups
Azure Service PrincipalAzureLinux VMs, managed disks, a NIC, optional Azure Monitor wiring
note

We derive these permission sets from the resources our Terraform declares and the SDK calls our engine makes. Yeedu doesn't ship a ready-made IAM policy, role definition or Proxmox role for any cloud, so treat each list as the minimum we know a deployment needs and widen it if your organisation's guardrails require more.

OCI: OCI API Key Pair

The Tenancy OCID, User OCID, Fingerprint and private key authenticate an API signing key. The Compartment OCID scopes every resource we create.

Terraform declarationKindCreated when
oci_identity_availability_domainsdataAlways. Resolves the Availability Domain you picked to its full OCI name
oci_core_instanceresourceAlways. Carries the VNIC, which reads your subnet and optional NSGs
oci_core_volumeresourceOne per disk in Disks Config, while the node runs or the scratch disk is kept
oci_core_volume_attachmentresourceOne per volume above

Scope the policy to the compartment named on the credential. The availability-domain lookup is the one statement that has to sit at tenancy level:

Allow group YeeduClusterProvisioners to inspect availability-domains in tenancy
Allow group YeeduClusterProvisioners to manage instance-family in compartment <compartment-name>
Allow group YeeduClusterProvisioners to manage volume-family in compartment <compartment-name>
Allow group YeeduClusterProvisioners to use subnets in compartment <compartment-name>
Allow group YeeduClusterProvisioners to use vnics in compartment <compartment-name>

Add this only when your cloud environment supplies network security groups:

Allow group YeeduClusterProvisioners to use network-security-groups in compartment <compartment-name>

Spot needs nothing extra on OCI. The preemptible configuration is a field on the instance, so manage instance-family already covers it. Cloud logging setup is skipped entirely for OCI, which is why no logging statement appears above.

OnPrem: Proxmox Basic Auth

The Username, to which the UI appends @pam, and the Password authenticate against the Proxmox VE API at your End Point. Unlike every other provider, on-prem start and stop go through Terraform rather than an SDK, by toggling the guest's started flag.

Terraform declarationKindCreated when
proxmox_virtual_environment_nodesdataAlways. Lists cluster nodes so we can pick one with free CPU and memory
proxmox_virtual_environment_vmsdataPer selected node. Reads existing guests and their tags to compute headroom
proxmox_virtual_environment_fileresourceAlways. The cloud-init user-data, written as a snippet on the local datastore
proxmox_virtual_environment_vmresourceAlways. Boot disk plus one disk per entry in Disks Config, on local-lvm

A role covering the guest lifecycle, both datastores and node audit is enough:

pveum role add YeeduClusterProvisioner -privs \
"VM.Allocate,VM.Audit,VM.Config.CPU,VM.Config.Cloudinit,VM.Config.Disk,VM.Config.HWType,\
VM.Config.Memory,VM.Config.Network,VM.Config.Options,VM.Monitor,VM.PowerMgmt,\
Datastore.Audit,Datastore.AllocateSpace,Datastore.AllocateTemplate,Sys.Audit"

pveum acl modify / -user yeedu@pam -role YeeduClusterProvisioner

VM.Monitor is there because we enable the QEMU guest agent and read the guest's IPv4 address back through it. Sys.Audit covers the node listing. Datastore.AllocateTemplate is what permits the snippet upload.

note

The snippet upload is easy to overlook. We write the node's cloud-init user-data to the local datastore, so that datastore must both accept the Snippets content type and be writable by this account. Otherwise the guest gets created and never bootstraps.

OnPrem: Custom S3a Credentials

This one provisions nothing. It never reaches a Terraform provider, and no resource in any module reads it.

What it does is authenticate the cluster node against an S3-compatible object store, in Yeedu's own on-prem setup a Ceph RADOS Gateway. The node's bootstrap exports the key pair as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and S3_ENDPOINT, then configures Spark with org.apache.hadoop.fs.s3a.S3AFileSystem and path-style access against that endpoint.

FieldUsed as
Access Key IDS3 access key on the node and in the Spark S3A config
Secret Access KeyS3 secret key
Custom S3a Endpointspark.hadoop.fs.s3a.endpoint, with path.style.access set to true

Its permissions come from your object store's own bucket policy, not from any cloud IAM. Grant read and write on the buckets you reference: the bucket behind a Dependency Repository, and the bucket in each s3:// or s3a:// mount source. Read-only mounts need read alone.

An OnPrem cloud environment still needs a Proxmox Basic Auth credential to provision anything.

GCP: Google Service Account

The service-account JSON authenticates Terraform, and by default the same account is attached to the node as its identity with the cloud-platform scope. That second use is why iam.serviceAccountUser appears below.

Terraform declarationKindCreated when
google_compute_addressresourceAlways. A reserved internal IP in your subnet, purpose GCE_ENDPOINT
google_compute_instanceresourceAlways. GPUs attached when CUDA acceleration is selected
google_compute_diskresourcePer disk in Disks Config, unless the disk type is local-ssd or scratch-disk
google_compute_attached_diskresourceOne per disk above

Two predefined roles cover the baseline. Grant them on the project named on the cloud environment:

roles/compute.instanceAdmin.v1
roles/iam.serviceAccountUser

If you'd rather define a custom role, this is the permission set our modules and SDK calls exercise:

compute.instances.create
compute.instances.delete
compute.instances.get
compute.instances.start
compute.instances.stop
compute.instances.attachDisk
compute.instances.detachDisk
compute.instances.setMetadata
compute.instances.setLabels
compute.instances.setTags
compute.instances.setServiceAccount
compute.disks.create
compute.disks.delete
compute.disks.get
compute.disks.use
compute.addresses.create
compute.addresses.delete
compute.addresses.get
compute.addresses.use
compute.subnetworks.use
compute.images.useReadOnly
compute.zoneOperations.get
iam.serviceAccounts.actAs

Three cases add to that. When the cloud environment's network project differs from its Project ID, the account needs roles/compute.networkUser on the network project, because we configure a second provider pointed at it. When Enable Public IP is on, add compute.subnetworks.useExternalIp. When CUDA is selected, add compute.acceleratorTypes.get and make sure the GPU quota exists in the zone.

Nothing on the GCP path creates logging infrastructure. Our engine treats cloud logging setup as a no-op for GCP.

AWS: AWS Access Secret Key Pair

Terraform declarationKindCreated when
aws_subnetdataAlways. Reads the availability zone of the subnet you supplied
aws_key_pairresourceAlways. Imports Yeedu's public key, one key pair per node
aws_instanceresourceOn-demand nodes only
aws_spot_instance_requestresourceSpot nodes only
aws_ebs_volumeresourcePer disk in Disks Config, while the node runs or the scratch disk is kept
aws_volume_attachmentresourceOne per volume above
aws_ec2_tagresourceSpot nodes only. Copies the label set onto the fulfilled instance

On top of that, the engine calls StartInstances, StopInstances and DescribeInstances directly, because restarting an instance that already exists through the SDK takes a couple of seconds where a full Terraform cycle takes closer to a minute, and it resolves an instance by its Name tag before starting it, which is why DescribeTags sits in the baseline alongside the describe calls for instances, images, volumes and subnets. It also creates nine CloudWatch log groups if they don't already exist: yeedu_bootstrap_log, yeedu_unstructured_log, yeedu_usi_reactors_logs, yeedu_log_collector_reactors, yeedu_log_collector_history_server, yeedu_copy_object_storage_logs, yeedu_workspace_files_sync_logs, yeedu_usi_reactors_monitor_logs and yeedu_usi_telegraf_logs.

Here's the baseline policy for an on-demand cluster.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "YeeduNodeLifecycle",
"Effect": "Allow",
"Action": [
"ec2:RunInstances",
"ec2:TerminateInstances",
"ec2:StartInstances",
"ec2:StopInstances",
"ec2:DescribeInstances",
"ec2:DescribeInstanceAttribute",
"ec2:DescribeInstanceTypes",
"ec2:DescribeImages",
"ec2:DescribeSubnets",
"ec2:ImportKeyPair",
"ec2:DescribeKeyPairs",
"ec2:DeleteKeyPair",
"ec2:CreateVolume",
"ec2:DeleteVolume",
"ec2:DescribeVolumes",
"ec2:AttachVolume",
"ec2:DetachVolume",
"ec2:CreateTags",
"ec2:DescribeTags",
"ec2:DeleteTags"
],
"Resource": "*"
},
{
"Sid": "YeeduLogGroups",
"Effect": "Allow",
"Action": [
"logs:DescribeLogGroups",
"logs:CreateLogGroup"
],
"Resource": "*"
}
]
}

Turning on Spot Instances (Experimental) switches the module to a spot request, and immediately after fulfilment we call ModifyInstanceMetadataOptions on the new instance to enable metadata tags:

{
"Sid": "YeeduSpotNodes",
"Effect": "Allow",
"Action": [
"ec2:RequestSpotInstances",
"ec2:DescribeSpotInstanceRequests",
"ec2:CancelSpotInstanceRequests",
"ec2:ModifyInstanceMetadataOptions"
],
"Resource": "*"
}

Attaching an instance profile through the cloud environment's cloud identity needs iam:PassRole for that role, since the profile name is passed straight to RunInstances.

warning

Leave the cloud identity empty and the node falls back to these same keys for its own work. The bootstrap script then exports them into the node's environment, and the credential additionally needs s3:GetObject and s3:ListBucket on the Yeedu software bucket, logs:CreateLogStream and logs:PutLogEvents for the awslogs agent, and ecr:GetAuthorizationToken plus ecr:BatchGetImage, ecr:GetDownloadUrlForLayer and ecr:BatchCheckLayerAvailability if your container images live in ECR. Attaching an instance profile is the cleaner option.

Azure: Azure Service Principal

The Client ID, Tenant ID, Client Secret and Subscription ID authenticate the service principal. The Resource Group on the cloud environment is where every VM resource lands.

Terraform declarationKindCreated when
azurerm_subnetdataAlways. Looked up by name in the network resource group
azurerm_network_interfaceresourceAlways
azurerm_public_ipresourceOnly when Enable Public IP is selected
azurerm_linux_virtual_machineresourceAlways. Priority flips to Spot for spot clusters
azurerm_managed_diskresourcePer disk in Disks Config, while the node runs or the scratch disk is kept
azurerm_virtual_machine_data_disk_attachmentresourceOne per disk above
azurerm_virtual_machine_extensionresourceLogging only. Installs AzureMonitorLinuxAgent
azurerm_monitor_data_collection_ruledataLogging only. Reads yeedu_usi_bootstrap_dcr and yeedu_usi_container_dcr
azurerm_monitor_data_collection_rule_associationresourceLogging only. Three associations per node
azurerm_monitor_data_collection_endpointdataLogging only
azurerm_log_analytics_workspacedataLogging only

Baseline actions for a custom role scoped to the subscription:

Microsoft.Resources/subscriptions/resourceGroups/read
Microsoft.Compute/virtualMachines/read
Microsoft.Compute/virtualMachines/write
Microsoft.Compute/virtualMachines/delete
Microsoft.Compute/virtualMachines/start/action
Microsoft.Compute/virtualMachines/deallocate/action
Microsoft.Compute/disks/read
Microsoft.Compute/disks/write
Microsoft.Compute/disks/delete
Microsoft.Network/networkInterfaces/read
Microsoft.Network/networkInterfaces/write
Microsoft.Network/networkInterfaces/delete
Microsoft.Network/networkInterfaces/join/action
Microsoft.Network/virtualNetworks/read
Microsoft.Network/virtualNetworks/subnets/read
Microsoft.Network/virtualNetworks/subnets/join/action

If you prefer built-in roles, Virtual Machine Contributor plus Network Contributor on the resource group is the closest fit to that list.

Public IP is the smallest add-on. Turn it on and the module creates and later deletes an azurerm_public_ip:

Microsoft.Network/publicIPAddresses/read
Microsoft.Network/publicIPAddresses/write
Microsoft.Network/publicIPAddresses/delete
Microsoft.Network/publicIPAddresses/join/action

Logging is the larger one. With it enabled, we create the custom log tables yeedu_usi_bootstrap_logs_CL and yeedu_usi_container_logs_CL in your Log Analytics workspace, create a data collection endpoint and two data collection rules, associate all three with the VM, and install the monitor agent extension:

Microsoft.Compute/virtualMachines/extensions/read
Microsoft.Compute/virtualMachines/extensions/write
Microsoft.Compute/virtualMachines/extensions/delete
Microsoft.Insights/dataCollectionEndpoints/read
Microsoft.Insights/dataCollectionEndpoints/write
Microsoft.Insights/dataCollectionRules/read
Microsoft.Insights/dataCollectionRules/write
Microsoft.Insights/dataCollectionRuleAssociations/read
Microsoft.Insights/dataCollectionRuleAssociations/write
Microsoft.Insights/dataCollectionRuleAssociations/delete
Microsoft.OperationalInsights/workspaces/read
Microsoft.OperationalInsights/workspaces/tables/read
Microsoft.OperationalInsights/workspaces/tables/write

Monitoring Contributor plus Log Analytics Contributor covers that block. One last case: if the cloud environment supplies a user-assigned managed identity as its cloud identity, the service principal also needs Microsoft.ManagedIdentity/userAssignedIdentities/assign/action on that identity. With no cloud identity set, the VM gets a system-assigned identity instead and nothing extra is required.

Acceleration

Acceleration* is a required radio group with three options:

OptionDescription
No AccelerationStandard CPU execution, no acceleration layer.
TurboYeedu's Turbo acceleration engine.
CUDAGPU (CUDA) acceleration.

The selected value is reflected in the CLUSTER DETAILS panel, and surfaces on the Job and Notebook forms as Turbo Acceleration: Enabled / Disabled.

Check the support badges on the Run Time Version row (see below) to confirm the runtime you pick advertises Cuda or Turbo support before selecting the matching acceleration mode.

Dependency Repository

Dependency Repository is an optional, clearable dropdown with a + button to create a new repository inline. It references a repository defined in the tenant-level Dependency Repositories module (/tenant/<tenant-id>/dependency-management).

The inline create form (Dependency Repository > New Repository) has these fields:

FieldValues / notes
Repository Name*Text
DescriptionText
Cloud Provider*OnPrem | GCP | AWS | Azure — note that OCI is not offered here, even though cloud environments do support OCI
Credential Name*Dropdown of credentials for that provider, with a + to create one inline
Bucket Name*Placeholder e.g., my-deps-bucket

Footer actions on that form: Reset, Create.

Dependencies

Run Time Version

Run Time Version* is a required dropdown. Each row in the list renders two groups:

  • Version: Spark, Scala, Python and Java versions — for example 3.5.3, 2.12.15, 3.9.5, 3.2.4.
  • Support: capability badges, each shown with a tick or a cross:
    • Notebook
    • Cuda
    • Turbo
    • Thrift Support

Use the badges to confirm a runtime supports the workload you intend to run on the cluster.

Compute

Compute* is its own required field (it is not part of the instance settings). Click Select Compute to open the Select Compute modal, or + to define a new compute shape.

Select Compute modal

The modal header states the architecture type, for example: Select Compute ( Architecture type : x86_64 ).

Every column is sortable and has its own filter input:

ColumnFilter placeholder
NameSearch By Name
CoresMin cores
Memorye.g., 256 GiB
Scratch Disk SizeScratch Disk / Size
No Of Disks
Total Disks Size
YCU/hrMax YCU
GPUsMin GPUs
GPU Memorye.g., 48 GiB

Rows are grouped under category headers. The categories depend on the selected cloud environment — on an OnPrem environment the groups are CUSTOM COMPUTE and GENERAL PURPOSE.

Select a single row with its radio button, then click Select.

Instances

FieldDescription
Min Instances*Minimum number of instances kept running.
Max Instances*Upper bound the cluster can scale to.
Number of Parallel Execution*Maximum number of concurrent executions per instance.

Note: there is no Workers per Node field in v2.10.1 — Number of Parallel Execution is the concurrency control on this form.

Instance Settings

Auto Shutdown

  • Reads "Stop Each Instance After <n> Minutes Of Idle Time".
  • Each instance is stopped once it has been idle for the configured number of minutes.

Labels

  • Add labels as key / value rows using the + button; remove a row with the trash icon.
  • Placeholders: e.g., team (key) and e.g., data-engineering (value).

Automatically Added Labels

A collapsible panel lists the labels Yeedu attaches to every cluster without any input from you:

LabelValue
resourceyeedu
vmyeedu_node
tenant_idThe tenant UUID
created_byThe creating user's email address
yeedu_envThe Yeedu environment name

Metastore

  • Select Metastore dropdown, with + to create a metastore inline.
  • Metastore types available in v2.10.1: AWS GLUE, DATABRICKS UNITY, HIVE.
  • The selected metastore type is shown as a badge in the Metastore column of the Clusters list.

Additional Configurations

Mounts

A collapsible section. When nothing is attached it shows the empty state "No Mounts Selected" with two buttons:

  • + New – create a new mount.
  • Attach – attach an existing mount.

Mounts

Spark Config

A collapsible section with 10 tabs:

TabPurpose
ConfigsSpark configuration key/value pairs.
Config SecretsConfiguration values sourced from secrets.
PackagesMaven/Spark packages.
JarsJAR dependencies.
ArchivesArchive files.
RepositoriesPackage repositories.
Py-filesPython file dependencies.
FilesAdditional files.
Env VariablesEnvironment variables.
Env SecretsEnvironment variables sourced from secrets.

The Configs tab has a Bulk Edit toggle, plus Key/Value rows with + (add) and trash (delete).

Spark Configs

Advanced Options

A collapsible section with 3 tabs: Init Script, Disks Config and Others.

Advanced Options

Init Script

A code editor with line numbers. Enter a script to run during node bootstrap.

Disks Config

FieldNotes
Disk TypeDropdown. The available values are provider-specific — on an OnPrem cloud environment the only value is local-lvm.
Size (GiB)Entered as size × quantity, with the computed total shown alongside. Helper text: "Enter size and quantity above".
IOPSProvider-specific; not shown for OnPrem environments.
Throughput (MBps)Provider-specific; not shown for OnPrem environments.

Disks config

Others

Termination Policy

  • "Terminate Cluster After <n> Minutes Of Inactivity." (the form ships with 240).
  • Keep Scratch Disk – checkbox, enabled by default.

Manage And SSH Permissions

  • Enable Public IP – checkbox.

Spot Instances (Experimental)

Provider-dependent: this section is not rendered for an OnPrem cloud environment. Availability on other providers depends on the selected cloud environment.

  • Uses discounted VMs (70–90% cheaper).
  • Best for stateless, retryable or batch workloads.
  • Can be interrupted at any time — unsuitable for long-running jobs.

CLUSTER DETAILS Panel

The right-hand column shows a live preview of the cluster as you configure it:

  • Cloud Provider
  • Cluster Type
  • Cloud Environment
  • Compute Type
  • Acceleration
  • Disk Volume
  • Runtime Version (with its capability badges)
  • Labels

The same panel component appears on the Create Job and Create Notebook forms, where it summarises the cluster you have selected.

Actions

ButtonBehaviour
ResetClears all fields on the form.
CreateCreates the cluster without starting it.
Create & StartCreates the cluster and immediately begins bootstrapping it.

Backend bootstrap time: ~6–7 minutes Ready to use in: ~1 minute after creation